.ig

  Copyright (c) 2020 Apple Inc.  All Rights Reserved.

..
.Dd June 19, 2020
.Os "Darwin"
.Dt DIAGTEST 1
.Sh NAME
.Nm diagtest
.Nd diagnostic info logging tool
.\"  SYNOPSIS
.Sh SYNOPSIS
.Nm
.Ar [command]
.\"  DESCRIPTION
.Sh DESCRIPTION
The
.Nm
utility exercises cctools libstuff error reporting SPI. It also exercises the
cctools' implementation of the CC_LOG_DIAGNOSTICS feature developed jointly by
XBS and clang. Other than printing warnings and error messages, and optionally
logging those messages to an XML-like file,
.Nm
does no real work.
.\"  COMMANDS
.Sh COMMANDS
.Bl -tag -width "XXkeepParent"
.It (default)
When run without a command,
.Nm
will display a series of warnings and errors.
.It Fl fatal
Display a single fatal error message which halts program flow.
.It Fl system_fatal
Display a single fatal error message (see above) along with an error string
representing a system `errno' value.
.It Fl mach_fatal
Display a single fatal error message (see above) along with an error string
representing a mach kernel error code.
.It Fl archive
Display a series of warnings, errors, and a fatal error generated by archive
processing code.
.El
.\"  CC_LOG_DIAGNOSTICS FILES
.Sh CC_LOG_DIAGNOSTICS FILES
CC_LOG_DIAGNOSTICS files contain warnings, errors, and other notes emitted by
one or more development tools. Diagnostic information is written in a
structured, machine-parsable format.
.Pp
CC_LOG_DIAGNOSTICS can be enabled by setting the `CC_LOG_DIAGNOSTICS'
environment variable and then running one or more tools that honor this format.
Warnings, errors, and other messages will be logged to standard error when the
tool exits normally. Diagnostic output can be routed instead to file via the
`CC_LOG_DIAGNOSTICS_FILE' environment variable; if a file already exists at
this path, new diagnostics will be appended at the end of the file.
.Pp
Each tool invocation produces a single XML fragment compatible with Apple's XML
property-list format, which this document calls a `Tool Entry'. The Tool Entry
contains a list of records representing individual diagnostics, which this
document calls a `Diagnostic Entry'.
.Pp
The Tool Entry is a dictionary (`<dict>') containing the following:
.Bl -column ".Em diagnostics" ".Em diagnostics" ".Em" -offset indent
.It Xo
.Em "Key" Ta Em "Type" Ta Em "Description"
.Xc
.It "tool" Ta "string" Ta
(Optional) The path to the tool that generated this diagnostic. This is an
extension to the CC_LOG_DIAGNOSTICS format introduced by cctools.
.It "diagnostics" Ta "array" Ta
An array of Diagnostic Entry records. The array may be empty.
.El
.Pp
The Diagnostic Entry is a dictionary containing the the following:
.Bl -column ".Em diagnostics" ".Em diagnostics" ".Em" -offset indent
.It Xo
.Em "Key" Ta Em "Type" Ta Em "Description"
.Xc
.It "level" Ta "string" Ta
cctools will emit one of the following: `warning', `error', `fatal error'.
clang and other tools may emit additional level types.
.It "ID" Ta "integer" Ta
While clang considers the ID field non-optional, cctools will always return
0 for this field. cctools may stop writing this field in the future.
.It "message" Ta "string" Ta
(Optional) A human readable error message. Clients may assume this is properly
formatted HTML. Note that cctools will embed file names and in the error
message directly, rather than supplying that information as discrete feels in
the Diagnostic Entry. Also note that cctools will always supply a diagnostic
message.
.El
.Pp
.Em Note :
because CC_LOG_DIAGNOSTICS files contain XML-blobs that have been catted
together, these files are not strictly XML. File contents can be wrapped by a
simple XML structure (`<array>$CONTENTS</array>') in order to easily consume
this data.
.\"  CC_LOG_DIAGNOSTICS EXAMPLE
.Sh CC_LOG_DIAGNOSTICS EXAMPLE
.Bd -literal
<dict>
  <key>tool</key>
  <string>/Users/mtrent/Debug/lipo</string>
  <key>diagnostics</key>
  <array>
    <dict>
      <key>level</key>
      <string>fatal error</string>
      <key>ID</key>
      <integer>0</integer>
      <key>message</key>
      <string>unknown flag: -cr</string>
    </dict>
  </array>
</dict>
.Ed
.\"  HISTORY
.Sh HISTORY
The CC_LOG_DIAGNOSTIC file format was jointly developed by Apple's XBS
build-system and clang. No formal description of the file format exists. The
format is largely promulgated by what clang always / optionally emits, what the
XBS parsers decode and expect, and what can be discovered via code inspection.
.\"  SEE ALSO
.Sh SEE ALSO
.Xr bitcode_strip 1 ,
.Xr codesign_allocate 1 ,
.Xr ctf_insert 1 ,
.Xr install_name_tool 1 ,
.Xr libtool 1 ,
.Xr lipo 1 ,
.Xr segedit 1 ,
.Xr strip 1
